feat!: add JavaScript API and enhance CLI behaviour #1394

Timeless0911 · 2025-12-12T08:56:21Z

Highlights 💡

New JavaScript API

This release introduces a new, comprehensive JavaScript API for Rslib.

Caution

This is a Breaking Change. The previously exposed informal API has been removed. You can switch to the new JavaScript API and refer to the docs below to re-integrate.

See the API docs for details:

Usage

Install Rslib: install the @rslib/core package:

npm add @rslib/core -D

Create an Rslib instance: call the createRslib method to create an Rslib instance:

import { createRslib } from '@rslib/core';

const rslib = await createRslib();

Call Rslib instance methods: use the rslib.build method which will build production outputs:

await rslib.build();

Summary

Provide a comprehensive JavaScript API

Type:

 type RslibInstance = {
     build(options?: BuildOptions): Promise<BuildResult>;
     inspectConfig(options?: InspectConfigOptions): Promise<InspectConfigResult>;
     startMFDevServer(options?: StartMFDevServerOptions): Promise<StartServerResult>;
     getRslibConfig(): Readonly<RslibConfig>;
     onAfterCreateRsbuild(callback: OnAfterCreateRsbuildFn): void;
 };
 
 function createRslib(options?: CreateRslibOptions): Promise<RslibInstance>;

Example:

 const rslib = await createRslib({
   config: {
     // Rslib configuration
   },
 });

 await rslib.build();

Refactor public API

Core methods:
- runCLI
- createRslib
- defineConfig
- loadConfig
- loadEnv
- mergeRslibConfig
Verbose Rslib/Rsbuild/Rspack configurations when running with DEBUG=rslib
Add --no-env cli options to control disable loading of .env files after refactor

Checklist

Copilot

Pull request overview

This PR refactors the CLI initialization and error handling to improve user experience. The main changes include renaming the public API from runCli to runCLI (following proper casing convention), consolidating CLI setup logic, and implementing smarter output formatting for different package managers. The refactor also adds a process title for easier identification and simplifies build error logging.

Key changes:

Renamed public API runCli to runCLI and consolidated CLI initialization logic into a new /cli/index.ts file
Removed the prepareCli function and integrated its functionality into the main CLI entry point
Enhanced package manager detection to handle output formatting for npx, Bun, and Node.js --run command
Introduced RSPACK_BUILD_ERROR constant to conditionally suppress redundant error messages
Renamed internal function initConfig to init for better clarity

Reviewed changes

Copilot reviewed 5 out of 6 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
packages/core/src/index.ts	Updated public API exports: renamed `runCli` to `runCLI` and removed `prepareCli` export
packages/core/src/cli/prepare.ts	Deleted file - functionality moved to `/cli/index.ts`
packages/core/src/cli/init.ts	Renamed function from `initConfig` to `init`
packages/core/src/cli/index.ts	New file consolidating CLI initialization with improved package manager detection and greeting logic
packages/core/src/cli/commands.ts	Added `RSPACK_BUILD_ERROR` constant and error filtering logic; renamed import from `initConfig` to `init`; updated import path
packages/core/bin/rslib.js	Simplified entry point to call `runCLI` directly without try-catch wrapper

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

packages/core/src/cli/commands.ts

packages/core/src/cli/index.ts

netlify · 2025-12-17T12:09:39Z

✅ Deploy Preview for rslib ready!

Name	Link
🔨 Latest commit	`08eb493`
🔍 Latest deploy log	https://app.netlify.com/projects/rslib/deploys/694cf66ba54b250008f29a03
😎 Deploy Preview	https://deploy-preview-1394--rslib.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

packages/core/src/cli/init.ts

fi3ework · 2025-12-25T08:48:44Z

website/docs/zh/api/start/index.mdx

+await rslib.build();
+```
+
+> 关于 Rslib 实例方法的更多介绍，请阅读 [Rslib instance](/api/javascript-api/instance) 章节。


it's not a quote, consider using ::: syntax

fi3ework · 2025-12-25T09:01:43Z

website/docs/zh/api/javascript-api/core.mdx

+
+const mergedConfig = mergeRslibConfig(config1, config2);
+
+console.log(mergedConfig);


what about console log the merged config here

fi3ework · 2025-12-25T09:02:48Z

website/docs/zh/api/javascript-api/core.mdx

+
+```ts
+// the same as `import { rspack } from '@rspack/core'`
+import { rspack } from '@rslib/core';


can we use two slash to annotate the type here?

fi3ework · 2025-12-25T09:05:35Z

website/docs/zh/api/javascript-api/instance.mdx

+const { rslibConfig, rsbuildConfig, bundlerConfigs } =
+  await rslib.inspectConfig();
+
+console.log(rslibConfig, rsbuildConfig, bundlerConfigs);


meaning less to console if we don't show what it will be like.

fi3ework · 2025-12-25T09:10:01Z

website/docs/zh/api/javascript-api/instance.mdx

+在非 watch 模式下，你也应该调用 `close()` 方法来结束构建，这会触发 Rsbuild 的 [onCloseBuild](https://rsbuild.rs/zh/plugins/dev/hooks#onclosebuild) 钩子，执行清理操作。
+
+```ts
+const buildResult = await rslib.build();


what about renaming to rslibInstance, calling close method on a result seems weird.

fi3ework · 2025-12-25T09:11:03Z

website/docs/zh/api/javascript-api/instance.mdx

+await buildResult.close();
+```
+
+在非 watch 模式下，你也应该调用 `close()` 方法来结束构建，这会触发 Rsbuild 的 [onCloseBuild](https://rsbuild.rs/zh/plugins/dev/hooks#onclosebuild) 钩子，执行清理操作。


so onCloseBuild will be called N + 1 times, if i manually invoked it N times?

This is align with rsbuild.build, the result is the return value of rsbuild.build, see https://rsbuild.rs/api/javascript-api/instance#close-build

yeah, it's fine. just curious.

fi3ework · 2025-12-25T09:11:49Z

website/docs/zh/api/javascript-api/types.mdx

+Rslib 实例的类型，对应 [createRslib](/api/javascript-api/core#createrslib) 方法的返回值。
+
+```ts
+import type { RslibInstance } from '@rslib/core';


Copilot AI review requested due to automatic review settings December 12, 2025 08:56

Copilot started reviewing on behalf of Timeless0911 December 12, 2025 08:57 View session

Copilot AI reviewed Dec 12, 2025

View reviewed changes

packages/core/src/cli/commands.ts Outdated Show resolved Hide resolved

packages/core/src/cli/commands.ts Show resolved Hide resolved

packages/core/src/cli/index.ts Show resolved Hide resolved

Timeless0911 force-pushed the js-api branch from cf5a661 to a1d0c42 Compare December 12, 2025 09:03

Timeless0911 marked this pull request as draft December 12, 2025 09:20

Timeless0911 force-pushed the js-api branch from a1d0c42 to 1c8a0d8 Compare December 15, 2025 07:23

Timeless0911 changed the title ~~refactor!: enhance CLI behaviour and logs~~ feat!: add JavaScript API and enhance CLI behaviour Dec 15, 2025

github-actions bot added the change: feat label Dec 15, 2025

Timeless0911 force-pushed the js-api branch 7 times, most recently from 8320ba4 to e2d7a37 Compare December 24, 2025 08:53

Timeless0911 marked this pull request as ready for review December 24, 2025 08:53

chenjiahan reviewed Dec 24, 2025

View reviewed changes

packages/core/src/cli/init.ts Outdated Show resolved Hide resolved

Timeless0911 force-pushed the js-api branch 3 times, most recently from 59330fc to f61d16c Compare December 24, 2025 10:06

Timeless0911 added 2 commits December 24, 2025 21:25

feat!: add JavaScript API and enhance CLI behaviour

1c7ba88

chore: update

2dfc38b

Timeless0911 force-pushed the js-api branch from 7ac06d8 to d85970f Compare December 24, 2025 13:25

chore: update

df0a98f

Timeless0911 force-pushed the js-api branch from d85970f to df0a98f Compare December 24, 2025 13:28

chore: update

eb74ce2

Timeless0911 force-pushed the js-api branch from 08eb493 to eb74ce2 Compare December 25, 2025 08:38

fi3ework reviewed Dec 25, 2025

View reviewed changes


		const mergedConfig = mergeRslibConfig(config1, config2);

		console.log(mergedConfig);

Uh oh!

feat!: add JavaScript API and enhance CLI behaviour #1394

Are you sure you want to change the base?

feat!: add JavaScript API and enhance CLI behaviour #1394

Uh oh!

Conversation

Timeless0911 commented Dec 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Highlights 💡

New JavaScript API

Usage

Summary

Related Links

Checklist

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

netlify bot commented Dec 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for rslib ready!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Timeless0911 commented Dec 12, 2025 •

edited

Loading

netlify bot commented Dec 17, 2025 •

edited

Loading